# Chapter 17

# Combining JavaScript, CGI, and SSI

CONTENTS

- Choosing the Right Tool for the Job
  - Comparing JavaScript with CGI
- The Basics of CGI
  - `GET` and `POST` Requests
  - Defining Requests in Forms
  - Name and Value Pairs
  - Environmental Variables
  - How CGI Programs Generate Output
- SSI: CGI Within a Web Page
  - Server-Side Include Directives
  - Enabling Server-Side Includes
- Languages for CGI and SSI
  - Perl
  - C and C++
  - Other Languages
- Creating a Simple CGI Program
- Installing a CGI Script
- Creating JavaScript Functions with SSI
- Workshop Wrap-Up
  - Next Steps
  - Q&A

In the beginning, the Web was a read-only medium-you could browse all sorts of information and link from site to site, but you couldn't really contribute anything yourself, except by clicking on an e-mail address.

The Common Gateway Interface (CGI) specification was the first step in making the Web more interactive. With new languages such as JavaScript and Java adding interactivity, you might wonder whether CGI has become obsolete. At the moment, this is far from true-CGI bears little resemblance to these languages, and can perform tasks impossible to other languages.

Because this is a book about JavaScript, this chapter doesn't go into detail about CGI -it's complicated enough to have merited a few books of its own. You will take a look at the basics of how CGI works, along with its close relative, SSI. This chapter presents a few examples of simple CGI scripts and explains how you can install scripts on your server. Finally, you'll learn how CGI, SSI, and JavaScript can work together to improve your Web pages.

NOTE
There are many books about CGI. I recommend Teach Yourself CGI Programming in Perl by Herrmann, and HTML & CGI Unleashed by December, Ginsburg et al., both published by Sams.net

## Choosing the Right Tool for the Job

Although CGI may become obsolete in the future, it won't be JavaScript that replaces it-they're very different things, and each has its uses. Here are the main differences:

- JavaScript executes on the client (like Java), and CGI executes on the server.
- CGI returns an entire document, and JavaScript may act on a tiny part of the page, such as a text field or the status line.
- CGI has access to information, such as the user's IP address, which JavaScript cannot access.
- JavaScript has access to information that CGI can't access-the links and anchors in the current page, for example.

### Comparing JavaScript with CGI

To illustrate the difference between JavaScript and CGI programs, let's look at one program that could be written using either-a program to display a random quotation when you load the page. I happen to have examples of both handy:

- I created a CGI program called the Random Quotations Page, which you can access at
  `http://www.starlingtech.com/quotes/randquote.cgi.
  ` The output of this program is shown in Figure 17.1.
  Figure 17.1 : A web page with random quotations, produced by a CGI program.
- A JavaScript program to display a random quotation was created in Chapter 7 "Real-Life Examples I." The output of this program is shown in Figure 17.2.
  Figure 17.2 : A random quotation page using JavaScript.

Using these pages as an example, here are a few comparisons of the capabilities of JavaScript and CGI:

- My CGI version has about 20,000 quotes available, all stored in a database on the server. This wouldn't be practical with JavaScript, because all the possible quotations would have to be loaded with the Web page.
- The JavaScript version is much, much faster, and it places no more load on the server than an ordinary Web page.
- The CGI version requires a server that supports CGI, access to it, and available disk space-things a low-priced Internet account may not provide. The JavaScript version, on the other hand, works even without a server-for example, you can load the file directly from the CD-ROM included with this book.
- The CGI version will work with any browser, but the JavaScript version requires Netscape, MSIE, or another JavaScript-compatible browser.
- If the quotation was displayed in a text field, the JavaScript version could update it at the touch of a button, without even reloading the page. CGI can't update part of a page.

As you can see, both JavaScript and CGI have advantages and disadvantages. Which you choose for a particular job will depend on what you need to do and what resources you and your users will have available.

## The Basics of CGI

CGI is a specification that enables programs to run on a Web server, accept data from the browser, and send data back in the form of a Web page. CGI programs can be written in any language the server understands.

TIP
CGI programs are sometimes referred to as CGI scripts, because many of the languages used for CGI are considered scripting languages.

When you're browsing the Web, you can access a CGI program in one of two ways:

- You can access it directly with an URL. The URL will often end in `.cgi` or `.pl`, although this is not a requirement.
- You can press the SUBMIT button on an HTML form. This sends the data you have entered in the form's elements to the CGI program on the server.

In technical terms, a request is being sent to the HTTP server to run the CGI program. After you send your request using either method, the CGI program can send output back to you in the form of a Web document. An entire document is always sent.

### `GET` and `POST` Requests

The requests sent to the server are sent using one of two methods. The difference between these lies in the way that data from your browser, or from form elements you filled out, are sent to the server. The two methods are the following:

- The `GET` method sends data in the URL itself. If you enter the URL of a CGI program directly, you are accessing it with the `GET` method. Forms can also use this method.
- The `POST` method sends data in a stream (standard input) after the request. This method enables larger amounts of data to be sent. The `POST` method is used exclusively by forms.

### Defining Requests in Forms

When you define an HTML form, you specify a CGI script to process the information and the method that will be used. You can do this using the following attributes to the `<FORM>` tag in HTML:

- `ACTION` specifies the URL of the CGI program that will receive the data when the SUBMIT button is pressed. You can also specify a `mailto` action here.
- `METHOD` specifies the request method and can be either `GET` or `POST`. Your CGI program will need to read the data using the same method.

As an example, the following `<FORM>` definition uses the `POST` method and sends the data to a program called `data.cgi`:

>     <FORM NAME="form1" ACTION = "data.cgi" METHOD = "POST">

NOTE
A JavaScript program cannot be used as the `ACTION` of a form, but it can work with the data before it is sent to the CGI program. Chapter 6describes the use of JavaScript with forms.

### Name and Value Pairs

A CGI program receives the data from the form as a group of name and value pairs. Each of these includes a name for the item and the item's value. For example, if the user entered `"Fred"` into a text field called `text1`, the name/value pair would have the name `text1` and the value `Fred`.

Part of the work of a CGI program is to decipher these name/value pairs. Depending on the method used, the program receives the data in one of two ways:

- For the `GET` method, the data is stored in an environmental variable called `QUERY_STRING`.
- For the `POST` method, the data is sent via the standard input.

In both cases, the data appears as a single large string, and you must separate it into names and values. For example, the following is how a request with two variable values might appear:

>     name=Fred&Address=123+Elm+Street

The `&` characters separate each name/value pair, and the `=` symbol separates each name from its value. In addition, notice that the spaces the user entered were replaced by `+` symbols. This is called URL encoding, and a CGI program must also take this into account. Along with replacing spaces with `+`, URL encoding replaces nonalphanumeric characters with escape codes; for example, the tilde (`~`) character becomes `%7E`.

#### Using URL Encoding and Decoding

CGI sends data to the server using URL encoding, and you may need to encode data you are sending. You may also run into this encoding using JavaScript; for example, data you send using the `mailto:` method is encoded this way. URLs sometimes include encoded characters, and you may need to decode them.

JavaScript includes two functions to let you work with encoding:

- The `escape()` function converts a string to URL-encoded form.
- The `unescape()` function converts a URL-encoded string to normal text.

With either function, simply use the text to be converted as the function's parameter.

### Environmental Variables

Along with the name/value pairs, a CGI program also receives information in environment variables. These include a variety of items about the server and the browser. Here are a few of the most common ones:

- `SERVER_SOFTWARE` is the version of the Web server in use.
- `REMOTE_ADDR` is the user's IP address.
- `REMOTE_HOST` is the user's host name.
- `REQUEST_METHOD` is the form's method, either `GET` or `POST`.
- `QUERY_STRING` is used to store the name/value pairs if the `GET` method is used.
- `HTTP_USER_AGENT` is the name of the browser the user is using (similar to JavaScript's `Navigator` object).

As you can see, these include some information that is not available to JavaScript. You'll see a way to make this information available to JavaScript in the task Creating JavaScript Functions with SSI, later in this chapter.

### How CGI Programs Generate Output

The final step in a CGI program is to display data back to the user. This may be as simple as a confirmation that the data was received, or it could be a complete Web page that is created based on the form data. The output of a CGI program is always displayed on a new, blank Web page.

Before a CGI program sends its output to the client, it must specify the type of document that will be created. These are MIME document types, and they can be of any type. Most CGI programs return an HTML document, using the `text/html` type.

The first line a CGI program outputs is a header that indicates the MIME type. The following header indicates an HTML document:

>     Content-type: text/html

NOTE
The `Content-type` header must always be followed by a blank line, before the actual output of the program begins

Optionally, a CGI program can send the user to an existing Web page, rather than outputting a document of its own. This is done using the `Location:` header, as in this example:

>     Location: http://www.starlingtech.com/books/javascript/

You should now have an understanding of the basics of CGI programming. You'll look at the specific languages a CGI program can use later in this chapter and also see an example of a CGI program.

## SSI: CGI Within a Web Page

An alternative to CGI is Server-Side Includes (SSI). These are special directives recognized by some Web servers, which enable you to execute a program or perform another function at any point within a Web page. SSI enables you to produce output as part of a Web page-in this way, it's similar to JavaScript.

An SSI program is similar to a CGI program-in some cases, the same program can be used. The main difference is in the way the program is called. An SSI program is called using an SSI directive in the HTML of the page. You'll look at the various directives that can be used in the next section.

Another difference between CGI and SSI is that an SSI program does not have access to form elements. It executes while the page is being sent to the client. An SSI program does, however, have access to the same environmental variables as CGI, as listed in the section titled Environmental Variables, earlier in this chapter.

### Server-Side Include Directives

SSI directives are interpreted by the server before being sent to the browser. Thus, they will be invisible to the user; only the output of an SSI program shows up in the HTML source.

Here is an example of an SSI directive that executes a program:

>     <-#exec program.ssi>

The following are the available commands for the latest SSI specification, called SSI+ 1.0:

- `echo` displays the value of an environmental variable.
- `include` adds the contents of another HTML document to the current document.
- `fsize` displays the size of a file; this is handy for images or downloadable programs.
- `fLastMod` displays the last-modified date for the current page.
- `exec` executes a CGI program.
- `email` sends an e-mail message.
- `if` enables you to include different text depending on the contents of a variable.
- `goto`, `label`, and `break` enable you to transfer control within a page.

### Enabling Server-Side Includes

To use SSI in a Web page, you need to enable the feature in the Web server. Because the server must preparse each document and interpret the SSI commands, the server can be slowed down, so it is usually not enabled by default.

The exact process to enable SSI for your pages will depend on the server software and on how the administrator has configured it. You may have to do one of the following:

- Use a command in the server's configuration file, or a local .htaccess file, to enable server-side includes.
- Make the HTML document executable, as with the UNIX command `chmod o+x document`.
- Consult your administrator to see whether the feature is available for your documents.

## Languages for CGI and SSI

As mentioned before, CGI isn't a language in itself-just a specification. CGI and SSI programs can be in any language the server (and the page developer) understands.

Several languages are commonly used for CGI and SSI. You'll look at a few of the most common ones in the sections that follow.

### Perl

Perl is by far the most common language used for CGI programs today. Perl is a versatile scripting language available for UNIX, DOS, and Windows NT platforms; practically every Web server has Perl available.

Like JavaScript, Perl is an interpreted language, so programs you download or create in Perl will not require compiling.

Perl's syntax is unique and can be confusing; however, you'll find that it has much in common with JavaScript. Many books are available that explain Perl fully; you can also refer to appendix C, "Online JavaScript Resources," for Web pages with information about Perl.

### C and C++

C and its object-oriented counterpart, C++, are also a popular choice for CGI. Unlike Perl, these languages must be compiled. If you download a public-domain program in these languages, you need to compile it to run on your particular server.

### Other Languages

Simple shell languages, such as sh and csh, are a common choice for simple CGI programs on UNIX platforms. Other possibilities include Python and TCL. Any language you know can be used, provided it's available on your server.

## Creating a Simple CGI Program

Although we won't explain every detail about Perl and CGI in this chapter, you may find this example helpful. The program in Listing 17.1 is a Perl program that sends the data entered in a form via e-mail.

> Listing 17.1. (EMAIL.PL) An example of a Perl CGI program to e-mail a form's data.

>     #!/usr/bin/perl

>     MAIN:  {
>         $sendmail = "|/usr/bin/sendmail user@address";
>         open(MAIL, $sendmail);
>     # Read POST data from standard input.
>     # The CONTENT_LENGTH variable tells us how
>     # many bytes to read.
>         read(STDIN, $request, $ENV{ÔCONTENT_LENGTH'});
>     # Split request into name/value pairs
>         %rqpairs = split(/[&=]/, $request));
>     # Convert URL syntax to ASCII
>         foreach (%rqpairs) {
>             tr/+/ /;
>             s/%(..)/pack("c",hex($1))/ge;
>         }
>     # headers for mail message
>          print MAIL "From: web@server\n";
>          print MAIL "To: user@address\n";
>          print MAIL "Subject: Form submission\n";
>     # Add each name/value pair to mail message
>         while (($key,$value) = each %rqpairs) {
>             print MAIL "$key = $value\n";
>         }
>     close MAIL;
>     # Output an HTML document
>     print "Content-type: text/html\n\n";
>         print "<HTML><HEAD><TITLE>Mail sent</TITLE>";
>         print "</HEAD><BODY>";
>         print "<H1>Mail sent</H1>";
>         print "Your mail was sent successfully.";
>         print "</BODY></HTML>";
>     exit 0;
>     }

This program reads the name and value pairs from a `POST` request and decodes them, then sends them in an e-mail message. This program may require minor changes to work on your server. You'll look at the process of installing a CGI program on a server in the next section.

TIP
Like JavaScript, Perl allows comments. The lines beginning with `#` in Listing 17.1 are comments, and they describe the purpose of each section of the program.

## Installing a CGI Script

Whether you learn to write CGI programs yourself or decide to use one of the many available public-domain CGI programs, you'll need to install it on your Web server to use it. This section explores the steps you follow to do this.

Depending on your situation, you might need to cooperate with the administrator of your server to perform these tasks. Some Internet providers do not allow CGI programs at all; you should check with the staff if you have any doubts or if the following steps don't work.

Here are the steps for installing a CGI program:

1. After creating or downloading the program, transfer it to the server. You will use an FTP program to do this. Depending on your Internet provider, the administrator may need to do this for you.
2. You may need to place the program in a specific directory, such as cgi-bin, to make it work. In addition, you may need to rename it with an extension such as .cgi. Again, this will depend on your Web server.
3. You will need to set the permissions correctly so that users can run the program. The UNIX command `chmod a+x filename` will usually work for this purpose.
4. Determine the URL for the program. This will depend on your server's configuration and the directory in which you have placed the program.
5. Place the correct URL in your HTML form and test the CGI program by submitting the form.

NOTE
Additional steps may be necessary, depending on the configuration of your Web server. Check with your administrator if the previous steps don't work.

## Creating JavaScript Functions with SSI

Here's an example of how SSI and JavaScript can work together. This case uses an SSI directive to create JavaScript "on the fly," in much the same way that JavaScript can create HTML "on the fly."

You learned earlier in this chapter that the CGI variables, such as `REMOTE_HOST`, are not available in JavaScript; using SSI, though, you can make them available to JavaScript. Listing 17.2 shows an HTML document that uses this feature.

> Listing 17.2. (SSIVAR.htm) Combining SSI and JavaScript.

>     <HTML>
>     <HEAD><TITLE>SSI and JavaScript</TITLE>
>     </HEAD>
>     <BODY>
>     <H1>CGI variables in JavaScript</H1>
>     <HR>
>     This program displays your current host in a
>     JavaScript dialog box.
>     <HR>
>     <SCRIPT LANGUAGE="JavaScript">
>     Host = "<-#echo var=REMOTE_HOST->";
>     window.alert("Your host is: " + Host);
>     </SCRIPT>
>     </BODY>
>     </HTML>

This JavaScript program simply sets a variable to the host name and displays it to the user by using the `window.alert()` method. The tricky part is that you have assigned the `Host` variable using an SSI `echo` directive.

The SSI will be interpreted by the host before sending the HTML document to the browser, so when the browser interprets it, the actual host will be in place of the `#echo` directive.

## Workshop Wrap-Up

In this chapter you learned about CGI and SSI, and how they can work with JavaScript:

- The basics of the CGI specification
- The environmental variables and name/value pairs sent to a CGI program
- The basics of the SSI specification
- How to write a simple CGI program and install it on the server
- How to use SSI and JavaScript together to expand JavaScript's capabilities

### Next Steps

Move on with one of the following:

- To learn to use JavaScript to validate a form before sending it to a CGI program, see Chapter 6 "Using Interactive Forms."
- To learn about another Web language-Java-and how it can work with JavaScript, see Chapter 16, "Integrating JavaScript with Java."
- To see examples of the techniques in this chapter, see Chapter 19, "Real-life Examples IV."
- To learn how JavaScript's capabilities may improve in the future, see Chapter 20, "The Future of JavaScript."

### Q&A

Q: | Can I use JavaScript to create SSI commands depending on a variable?
A: | No. By the time the browser sees the page, the SSI commands have already been parsed by the server. You can use SSI to create JavaScript, but not the other way around.
Q: | When I install a CGI script and try to use it, I get an error indicating that the program doesn't exist. What's the solution?
A: | This is a common error in CGI, but it can have many causes. It can mean that your program actually doesn't exist, that it has the wrong permissions or is in the wrong place, or that the `Content-type:` header is not being sent correctly by the script.
Q: | Can I include a JavaScript program in the output of a CGI program?
A: | Yes. This can be useful for creating JavaScript programs based on data entered in a form.
Q: | Aside from using a form, is there any other way to send data to a CGI program from JavaScript?
A: | You could also send data in the URL. Use the `escape()` function to convert it, then add it to the CGI program's URL as a query using a question mark: `prog.cgi?var1=John+Smith` sends the name `var1` and the value `John Smith` to the program. Set the `location.href` property to activate the script. CGI programs can also set cookie values you set using JavaScript.